docs(skills): objectstack-query factual sweep — 17 false behavioral claims corrected, -33 lines - #13740

Fixes #13717
Part of #13658

Flight ③ of the published-skills factual sweep: every behavioral claim in
skills/objectstack-query/** verified against the implementation, with executed
probes wherever a claim is behavior-bearing. Method per #13658 comments
5474435934 / 5474464789 / 5475032239 (content-class targeting first, both error
directions, cross-file contradiction scan first).

Governed surface — draft, human merge only. No ratchet ceiling raised.

Budget

Every ceiling is shrink-only and every file came in under it. references/_index.md
was verified (all nine schema paths resolve at origin/main) and needed no edit.

Corrections — 落点 | before | after

17 FALSE claims corrected. 11 of the 17 are the deader-than-real direction — the
docs marked a shipped capability dead or unreachable. That matches flight ②'s
majority finding.

Plus derived-claim repairs in evals/README.md (items 4, 5, 6, 7) whose rubrics
encoded the same falsehoods — item 6 told the model to fail an answer using
having, which is enforced.

One further correction, a framing rather than a surface claim: rules/filters.md
labelled { deleted_at: null } a ❌ Wrong null check. Measured, a bare null
comparand lowers to IS NULL on both the in-memory evaluator and the SQL driver
and returns exactly the same rows as $null: true. The recommendation to prefer
$null is kept (it is the only spelling of IS NOT NULL); the false "wrong"
label is not.

Cross-file contradiction scan (run first, per the method)

Four contradictions inside the package; every one settled against the
implementation, not against the other document:

1. having — SKILL.md and rules/aggregation.md say ✅ Enforced; evals/README.md
   said "schema-reserved, silently dropped". Implementation: enforced.
2. compareTo — SKILL.md said bare string, rules/aggregation.md says
   { kind, dimension? }. Implementation: the object form; the string is retired.
3. windowFunctions — SKILL.md and rules/aggregation.md say REMOVED/tombstoned;
   evals/README.md said "schema-reserved". Implementation: removed.
4. Per-aggregation filter — three files agreed it was inert; all three were wrong.
   (Agreement between documents is not evidence — this is the case the method's
   "never verify one document against another" rule exists for.)

Evidence — executed probes

Non-vacuity control satisfied several times over; every probe below ran a control
that discriminates.

• $field cross-field. In-memory evaluator over three rows (over 200/100,
  under 50/100, equal 100/100): $gt → ["over"], $eq → ["equal"],
  $lt → ["under"]. Control, a plain literal $gt: 150 on the same harness →
  ["over"]. Through SqlDriver on better-sqlite3, same fixture pushed down:
  $gt { $field: 'budget' } → ["over"]. The claim under test predicted zero rows
  on both paths.
• count_distinct on SQL. SqlDriver.aggregate with
  { function: 'count_distinct', field: 'dept', alias: 'n' } → [{"n":2}].
  Control, an undeclared function median on the same driver → threw
  INVALID_QUERY/400, so a refusal would have been visible.
• Per-aggregation filter. engine.aggregate('deal', …) over 4 rows
  (2 closed_won): [{"total_deals":4,"won_deals":2}]. The claim under test
  predicted won_deals: 4.
• having. 4 orders across 3 customers, having: { order_count: { $gt: 1 } }
  → [{"customer_id":"c1","order_count":2}]. Also confirms groupBy auto-selects
  the grouped column without listing it in fields.
• Search expansion. expandSearchToFilter('machine learning', …) →
  {"$and":[{"$or":[{"title":{"$icontains":"machine"}},{"content":{"$icontains":"machine"}}]},{"$or":[…"learning"…]}]};
  single term 'apollo' → a bare {"$or":[…]}.
• Case sensitivity. Rows Apollo/apollo: $contains: 'apollo' →
  ["apollo"]; $icontains: 'apollo' → ["Apollo","apollo"].
• Parse oracle, tombstones. QuerySchema.safeParse REJECTS cursor, joins,
  windowFunctions, distinct, aggregations[].distinct, array_agg,
  string_agg, and an aggregation with no alias; ACCEPTS all six aggregation
  functions, top, having, aggregations[].filter, the fifteen documented filter
  operators, and a $field comparand.
• Parse oracle, analytics. DashboardWidgetSchema REJECTS
  compareTo: 'previousPeriod' and categoryGranularity, ACCEPTS
  compareTo: { kind: 'previousPeriod' }; ReportSchema REJECTS
  groupingsDown/groupingsAcross, ACCEPTS dataset + rows + columns + values.
• Token vocabulary (all VERIFIED). isDateMacroToken LIVE for today,
  yesterday, tomorrow, now, current_month_start, last_quarter_end,
  next_year_start, month_start, 30_days_ago, 2_weeks_from_now,
  current_year_start, current_year_end; isContextToken LIVE for
  current_user_id, current_org_id; both DEAD for the two near-misses the doc
  names as near-misses (current_user, this_quarter_start). Parameterised forms
  live for all six declared units in both directions.
• $exists / $null (prior art of docs(skills): $exists means HAS A VALUE — retire the MongoDB $exists claim from objectstack-query #13577, re-verified at origin/main).
  Rows valued / null / key-absent: $exists: true → ["v"]; $null: true →
  ["n","absent"]. HAS A VALUE, confirmed; both rows correct as merged.
• Null comparand. { d: null } → ["n","absent"] in memory and ["n"] on
  SQL — identical to { d: { $null: true } } on each path. $null: false → ["v"].

Verified without execution, by enumerating the implementation: MAX_EXPAND_DEPTH = 3;
resolveFilterTokens reached from exactly find/findOne/count/aggregate/
update/delete; SqlDriver.findWithWindowFunctions() exists and its builder
emits argument-less FUNC() (its own docblock says the skills' aggregation rules
say the same); the six search knobs each carry an [EXPERIMENTAL — not enforced]
.describe() marker; the $searchFields dotted-path refusal text quoted in
SKILL.md matches the ingress gate word for word; the flow-filter rule really is
severity: inFilter ? 'error' : 'warning'; resolveDateMacros / resolveContextTokens
exist in objectui @object-ui/core; all four Skill Boundaries targets exist;
compatibility: @objectstack/spec 17.x (Zod v4) matches 17.2.0 on zod ^4.4.3.

Gates

Derived from the real diff with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack
in the worktree, on a NON-stale tree (the branch was merged up to origin/main
0f911eb9 first — the first derivation warned that lint.yml and
cross-package-test-inputs.mjs, which are themselves families in the list, were
stale). 13 families, all run at d601906b, the final commit:

Exit codes captured with cmd > log 2>&1; EXIT=$? — before any pipe.

check-test-completeness exit 3 is the script's own PREREQUISITE NOT MET branch:
it grades a saved turbo run test log, and the derived family names it with no
argument. Its output says so verbatim and instructs the local reader to record it
as NOT MEASURED. Not a finding.

check:skill-examples — named in the dispatch brief, not in the derived family
list, and the derivation is right: that gate type-checks only fences marked with an
os:check HTML-comment marker, and skills/objectstack-query/** carries zero
such markers (control: objectstack-ui, objectstack-i18n and objectstack-formula
each carry them, so the search discriminates). Its population here is empty. Two
bounded foreground attempts to run it anyway were blocked by its
@objectstack/client-react build prerequisite, whose closure fails on pre-existing
type-only import gaps in @objectstack/runtime and @objectstack/verify
(Cannot find module '@objectstack/rest') — unrelated to this diff, and both
attempts hit the container's foreground cap. CI runs the gate on every PR regardless.

No changeset

Pure skills/** diff, releasing nothing. Convention verified against origin/main
rather than assumed: the last six commits touching skills/** — the three
objectstack-data sweep PRs, the objectstack-formula sweep, the $exists correction,
and the pm-dispatch rules PR — carry zero .changeset/ files between them. The
skip-changeset label is applied to this PR.

NOT MEASURABLE (recorded, never annotated into the files)

Nine claims could not be settled from a package-scoped flight; none was corrected
and none is known false. They are the cross-package-runtime class flight ① named:

1. Expand resolves via batch $in queries "not N+1" — the QueryAST.expand
.describe() asserts it and MAX_EXPAND_DEPTH = 3 is read directly, but proving
   the batching (rather than reading the claim) needs a driver call-count harness
   over a relational fixture.
2. Expand applies fields + where only, ignoring per-parent limit/offset/
   orderBy — same fixture gap.
3. $icontains ASCII-folding domain, and the __search pinyin companion column
   behind OS_SEARCH_PINYIN_ENABLED — needs a provisioned companion column.
4. search fields narrowing answering 400 INVALID_FIELD over the REST/protocol
   ingress — the refusal text was matched in metadata-protocol, but the HTTP
   status pairing needs a live server.
5. select/status label→value mapping in search — the unit suite pins
   { industry: { $in: ['retail'] } }; not re-run here against a real object.
6. Date-bucket push-down vs in-memory fallback agreeing "including the column keys"
   — the alias-renames-the-projection half was measured
   ([{"quarter":"2025-Q1","revenue":30},{"quarter":"2025-Q2","revenue":5}]), the
   two-tier agreement across a real DATE_TRUNC dialect was not.
7. ISO-8601 weeks starting Monday — asserted by DateGranularity's docblock; not
   executed across a week boundary.
8. os validate / os build / npm run validate failing a dashboard widget whose
   dataset/dimensions/values do not resolve (ADR-0021) — needs a scaffolded
   project.
9. Offset-pagination performance claims ("degrades on large offsets", keyset "O(1)")
   — true of relational engines generally; not benchmarked here, and not the kind of
   claim this sweep's oracle can settle.

Out-of-scope finding

packages/objectql/src/engine.ts carries a stale docblock describing the ADR-0061
search expansion as "a server-resolved cross-field $or of $contains" — the same
sentence this PR corrects in the published skill. The implementation next door
(search-filter.ts) emits $icontains and documents the correction explicitly. An
internal comment, outside this PR's file surface; reported for filing rather than
fixed here.

Generated by Claude Code

Generated by Claude Code